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 -opt, --show-options
282 Write a list of all options used to the .LOG file. Please see
283 --dump-options for a simpler way to do this.
284 -f, --force-read-binary
286 Force perltidy to process binary files. To avoid producing
287 excessive error messages, perltidy skips files identified by the
288 system as non-text. However, valid perl scripts containing binary
289 data may sometimes be identified as non-text, and this flag forces
290 perltidy to process them.
291
293 Basic Options
294 -l=n, --maximum-line-length=n
295 The default maximum line length is n=80 characters. Perltidy will
296 try to find line break points to keep lines below this length.
297 However, long quotes and side comments may cause lines to exceed
298 this length. Setting -l=0 is equivalent to setting -l=(a large
299 number).
300 -i=n, --indent-columns=n
302 Use n columns per indentation level (default n=4).
303 tabs
305 Using tab characters will almost certainly lead to future
306 portability and maintenance problems, so the default and
307 recommendation is not to use them. For those who prefer tabs,
308 however, there are two different options.
309 Except for possibly introducing tab indentation characters, as
311 outlined below, perltidy does not introduce any tab characters into
312 your file, and it removes any tabs from the code (unless requested
313 not to do so with -fws). If you have any tabs in your comments,
314 quotes, or here-documents, they will remain.
315 -et=n, --entab-leading-whitespace
317 This flag causes each n initial space characters to be replaced
318 by one tab character. Note that the integer n is completely
319 independent of the integer specified for indentation parameter,
320 -i=n.
321 -t, --tabs
323 This flag causes one leading tab character to be inserted for
324 each level of indentation. Certain other features are
325 incompatible with this option, and if these options are also
326 given, then a warning message will be issued and this flag will
327 be unset. One example is the -lp option.
328 -syn, --check-syntax
330 This flag causes perltidy to run "perl -c -T" to check syntax of
331 input and output. (To change the flags passed to perl, see the
332 next item, -pscf). The results are written to the .LOG file, which
333 will be saved if an error is detected in the output script. The
334 output script is not checked if the input script has a syntax
335 error. Perltidy does its own checking, but this option employs
336 perl to get a "second opinion".
337 If perl reports errors in the input file, they will not be reported
339 in the error output unless the --warning-output flag is given.
340 The default is not to do this type of syntax checking (although
342 perltidy will still do as much self-checking as possible). The
343 reason is that it causes all code in BEGIN blocks to be executed,
344 for all modules being used, and this opens the door to security
345 issues and infinite loops when running perltidy.
346 -pscf=s, -perl-syntax-check-flags=s
348 When perl is invoked to check syntax, the normal flags are "-c -T".
349 In addition, if the -x flag is given to perltidy, then perl will
350 also be passed a -x flag. It should not normally be necessary to
351 change these flags, but it can be done with the -pscf=s flag. For
352 example, if the taint flag, "-T", is not wanted, the flag could be
353 set to be just -pscf=-c.
354 Perltidy will pass your string to perl with the exception that it
356 will add a -c and -x if appropriate. The .LOG file will show
357 exactly what flags were passed to perl.
358 -io, --indent-only
360 This flag is used to deactivate all formatting and line break
361 changes within non-blank lines of code. When it is in effect, the
362 only change to the script will be to the indentation and blank
363 lines. And any flags controlling whitespace and newlines will be
364 ignored. You might want to use this if you are perfectly happy
365 with your whitespace and line breaks, and merely want perltidy to
366 handle the indentation. (This also speeds up perltidy by well over
367 a factor of two, so it might be useful when perltidy is merely
368 being used to help find a brace error in a large script).
369 Setting this flag is equivalent to setting --freeze-newlines and
371 --freeze-whitespace.
372 If you also want to keep your existing blank lines exactly as they
374 are, you can add --freeze-blank-lines.
375 -ole=s, --output-line-ending=s
377 where s="win", "dos", "unix", or "mac". This flag tells perltidy
378 to output line endings for a specific system. Normally, perltidy
379 writes files with the line separator character of the host system.
380 The "win" and "dos" flags have an identical result.
381 -ple, --preserve-line-endings
383 This flag tells perltidy to write its output files with the same
384 line endings as the input file, if possible. It should work for
385 dos, unix, and mac line endings. It will only work if perltidy
386 input comes from a filename (rather than stdin, for example). If
387 perltidy has trouble determining the input file line ending, it
388 will revert to the default behavior of using the line ending of the
389 host system.
390 Code Indentation Control
392 -ci=n, --continuation-indentation=n
393 Continuation indentation is extra indentation spaces applied when a
394 long line is broken. The default is n=2, illustrated here:
395 my $level = # -ci=2
397 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
398 The same example, with n=0, is a little harder to read:
400 my $level = # -ci=0
402 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
403 The value given to -ci is also used by some commands when a small
405 space is required. Examples are commands for outdenting labels,
406 -ola, and control keywords, -okw.
407 When default values are not used, it is suggested that the value n
409 given with -ci=n be no more than about one-half of the number of
410 spaces assigned to a full indentation level on the -i=n command.
411 -sil=n --starting-indentation-level=n
413 By default, perltidy examines the input file and tries to determine
414 the starting indentation level. While it is often zero, it may not
415 be zero for a code snippet being sent from an editing session. If
416 the default method does not work correctly, or you want to change
417 the starting level, use -sil=n, to force the starting level to be
418 n.
419 List indentation using -lp, --line-up-parentheses
421 By default, perltidy indents lists with 4 spaces, or whatever value
422 is specified with -i=n. Here is a small list formatted in this
423 way:
424 # perltidy (default)
426 @month_of_year = (
427 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
428 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
429 );
430 Use the -lp flag to add extra indentation to cause the data to
432 begin past the opening parentheses of a sub call or list, or
433 opening square bracket of an anonymous array, or opening curly
434 brace of an anonymous hash. With this option, the above list would
435 become:
436 # perltidy -lp
438 @month_of_year = (
439 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
440 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
441 );
442 If the available line length (see -l=n ) does not permit this much
444 space, perltidy will use less. For alternate placement of the
445 closing paren, see the next section.
446 This option has no effect on code BLOCKS, such as if/then/else
448 blocks, which always use whatever is specified with -i=n. Also,
449 the existence of line breaks and/or block comments between the
450 opening and closing parens may cause perltidy to temporarily revert
451 to its default method.
452 Note: The -lp option may not be used together with the -t tabs
454 option. It may, however, be used with the -et=n tab method.
455 In addition, any parameter which significantly restricts the
457 ability of perltidy to choose newlines will conflict with -lp and
458 will cause -lp to be deactivated. These include -io, -fnl, -nanl,
459 and -ndnl. The reason is that the -lp indentation style can
460 require the careful coordination of an arbitrary number of break
461 points in hierarchical lists, and these flags may prevent that.
462 -cti=n, --closing-token-indentation
464 The -cti=n flag controls the indentation of a line beginning with a
465 ")", "]", or a non-block "}". Such a line receives:
466 -cti = 0 no extra indentation (default)
468 -cti = 1 extra indentation such that the closing token
469 aligns with its opening token.
470 -cti = 2 one extra indentation level if the line looks like:
471 ); or ]; or };
472 -cti = 3 one extra indentation level always
473 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
475 section).
476 # perltidy -lp -cti=1
478 @month_of_year = (
479 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
480 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
481 );
482 # perltidy -lp -cti=2
484 @month_of_year = (
485 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
486 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
487 );
488 These flags are merely hints to the formatter and they may not
490 always be followed. In particular, if -lp is not being used, the
491 indentation for cti=1 is constrained to be no more than one
492 indentation level.
493 If desired, this control can be applied independently to each of
495 the closing container token types. In fact, -cti=n is merely an
496 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
497 --closing-paren-indentation controls )'s, -csbi or
498 --closing-square-bracket-indentation controls ]'s, -cbi or
499 --closing-brace-indentation controls non-block }'s.
500 -icp, --indent-closing-paren
502 The -icp flag is equivalent to -cti=2, described in the previous
503 section. The -nicp flag is equivalent -cti=0. They are included
504 for backwards compatability.
505 -icb, --indent-closing-brace
507 The -icb option gives one extra level of indentation to a brace
508 which terminates a code block . For example,
509 if ($task) {
511 yyy();
512 } # -icb
513 else {
514 zzz();
515 }
516 The default is not to do this, indicated by -nicb.
518 -olq, --outdent-long-quotes
520 When -olq is set, lines which is a quoted string longer than the
521 value maximum-line-length will have their indentation removed to
522 make them more readable. This is the default. To prevent such
523 out-denting, use -nolq or --nooutdent-long-lines.
524 -oll, --outdent-long-lines
526 This command is equivalent to --outdent-long-quotes and
527 --outdent-long-comments, and it is included for compatibility with
528 previous versions of perltidy. The negation of this also works,
529 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
530 and -nolc.
531 Outdenting Labels: -ola, --outdent-labels
533 This command will cause labels to be outdented by 2 spaces (or
534 whatever -ci has been set to), if possible. This is the default.
535 For example:
536 my $i;
538 LOOP: while ( $i = <FOTOS> ) {
539 chomp($i);
540 next unless $i;
541 fixit($i);
542 }
543 Use -nola to not outdent labels.
545 Outdenting Keywords
547 -okw, --outdent-keywords
548 The command -okw will will cause certain leading control
549 keywords to be outdented by 2 spaces (or whatever -ci has been
550 set to), if possible. By default, these keywords are "redo",
551 "next", "last", "goto", and "return". The intention is to make
552 these control keywords easier to see. To change this list of
553 keywords being outdented, see the next section.
554 For example, using "perltidy -okw" on the previous example
556 gives:
557 my $i;
559 LOOP: while ( $i = <FOTOS> ) {
560 chomp($i);
561 next unless $i;
562 fixit($i);
563 }
564 The default is not to do this.
566 Specifying Outdented Keywords: -okwl=string,
568 --outdent-keyword-list=string
569 This command can be used to change the keywords which are
570 outdented with the -okw command. The parameter string is a
571 required list of perl keywords, which should be placed in
572 quotes if there are more than one. By itself, it does not
573 cause any outdenting to occur, so the -okw command is still
574 required.
575 For example, the commands "-okwl="next last redo goto" -okw"
577 will cause those four keywords to be outdented. It is probably
578 simplest to place any -okwl command in a .perltidyrc file.
579 Whitespace Control
581 Whitespace refers to the blank space between variables, operators, and
582 other code tokens.
583 -fws, --freeze-whitespace
585 This flag causes your original whitespace to remain unchanged, and
586 causes the rest of the whitespace commands in this section, the
587 Code Indentation section, and the Comment Control section to be
588 ignored.
589 Tightness of curly braces, parentheses, and square brackets.
591 Here the term "tightness" will mean the closeness with which pairs
592 of enclosing tokens, such as parentheses, contain the quantities
593 within. A numerical value of 0, 1, or 2 defines the tightness,
594 with 0 being least tight and 2 being most tight. Spaces within
595 containers are always symmetric, so if there is a space after a "("
596 then there will be a space before the corresponding ")".
597 The -pt=n or --paren-tightness=n parameter controls the space
599 within parens. The example below shows the effect of the three
600 possible values, 0, 1, and 2:
601 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
603 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
604 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
605 When n is 0, there is always a space to the right of a '(' and to
607 the left of a ')'. For n=2 there is never a space. For n=1, the
608 default, there is a space unless the quantity within the parens is
609 a single token, such as an identifier or quoted string.
610 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
612 controls the space within square brackets, as illustrated below.
613 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
615 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
616 $width = $col[$j + $k] - $col[$j]; # -sbt=2
617 Curly braces which do not contain code blocks are controlled by the
619 parameter -bt=n or --brace-tightness=n.
620 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
622 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
623 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
624 And finally, curly braces which contain blocks of code are
626 controlled by the parameter -bbt=n or --block-brace-tightness=n as
627 illustrated in the example below.
628 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
630 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
631 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
632 -sts, --space-terminal-semicolon
634 Some programmers prefer a space before all terminal semicolons.
635 The default is for no such space, and is indicated with -nsts or
636 --nospace-terminal-semicolon.
637 $i = 1 ; # -sts
639 $i = 1; # -nsts (default)
640 -sfs, --space-for-semicolon
642 Semicolons within for loops may sometimes be hard to see,
643 particularly when commas are also present. This option places
644 spaces on both sides of these special semicolons, and is the
645 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
646 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
648 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
649 -asc, --add-semicolons
651 Setting -asc allows perltidy to add any missing optional semicolon
652 at the end of a line which is followed by a closing curly brace on
653 the next line. This is the default, and may be deactivated with
654 -nasc or --noadd-semicolons.
655 -dsm, --delete-semicolons
657 Setting -dsm allows perltidy to delete extra semicolons which are
658 simply empty statements. This is the default, and may be
659 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
660 are not deleted, however, if they would promote a side comment to a
661 block comment).
662 -aws, --add-whitespace
664 Setting this option allows perltidy to add certain whitespace
665 improve code readability. This is the default. If you do not want
666 any whitespace added, but are willing to have some whitespace
667 deleted, use -naws. (Use -fws to leave whitespace completely
668 unchanged).
669 -dws, --delete-old-whitespace
671 Setting this option allows perltidy to remove some old whitespace
672 between characters, if necessary. This is the default. If you do
673 not want any old whitespace removed, use -ndws or
674 --nodelete-old-whitespace.
675 Detailed whitespace controls around tokens
677 For those who want more detailed control over the whitespace around
678 tokens, there are four parameters which can directly modify the
679 default whitespace rules built into perltidy for any token. They
680 are:
681 -wls=s or --want-left-space=s,
683 -nwls=s or --nowant-left-space=s,
685 -wrs=s or --want-right-space=s,
687 -nwrs=s or --nowant-right-space=s.
689 These parameters are each followed by a quoted string, s,
691 containing a list of token types. No more than one of each of
692 these parameters should be specified, because repeating a command-
693 line parameter always overwrites the previous one before perltidy
694 ever sees it.
695 To illustrate how these are used, suppose it is desired that there
697 be no space on either side of the token types = + - / *. The
698 following two parameters would specify this desire:
699 -nwls="= + - / *" -nwrs="= + - / *"
701 (Note that the token types are in quotes, and that they are
703 separated by spaces). With these modified whitespace rules, the
704 following line of math:
705 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
707 becomes this:
709 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
711 These parameters should be considered to be hints to perltidy
713 rather than fixed rules, because perltidy must try to resolve
714 conflicts that arise between them and all of the other rules that
715 it uses. One conflict that can arise is if, between two tokens,
716 the left token wants a space and the right one doesn't. In this
717 case, the token not wanting a space takes priority.
718 It is necessary to have a list of all token types in order to
720 create this type of input. Such a list can be obtained by the
721 command --dump-token-types. Also try the -D flag on a short
722 snippet of code and look at the .DEBUG file to see the
723 tokenization.
724 WARNING Be sure to put these tokens in quotes to avoid having them
726 misinterpreted by your command shell.
727 Space between specific keywords and opening paren
729 When an opening paren follows a Perl keyword, no space is
730 introduced after the keyword, unless it is (by default) one of
731 these:
732 my local our and or eq ne if else elsif until unless
734 while for foreach return switch case given when
735 These defaults can be modified with two commands:
737 -sak=s or --space-after-keyword=s adds keywords.
739 -nsak=s or --nospace-after-keyword=s removes keywords.
741 where s is a list of keywords (in quotes if necessary). For
743 example,
744 my ( $a, $b, $c ) = @_; # default
746 my( $a, $b, $c ) = @_; # -nsak="my local our"
747 To put a space after all keywords, see the next item.
749 Space between all keywords and opening parens
751 When an opening paren follows a function or keyword, no space is
752 introduced after the keyword except for the keywords noted in the
753 previous item. To always put a space between a function or keyword
754 and its opening paren, use the command:
755 -skp or --space-keyword-paren
757 You will probably also want to use the flag -sfp (next item) too.
759 Space between all function names and opening parens
761 When an opening paren follows a function the default is not to
762 introduce a space. To cause a space to be introduced use:
763 -sfp or --space-function-paren
765 myfunc( $a, $b, $c ); # default
767 myfunc ( $a, $b, $c ); # -sfp
768 You will probably also want to use the flag -skp (previous item)
770 too.
771 Trimming whitespace around "qw" quotes
773 -tqw or --trim-qw provide the default behavior of trimming spaces
774 around multi-line "qw" quotes and indenting them appropriately.
775 -ntqw or --notrim-qw cause leading and trailing whitespace around
777 multi-line "qw" quotes to be left unchanged. This option will not
778 normally be necessary, but was added for testing purposes, because
779 in some versions of perl, trimming "qw" quotes changes the syntax
780 tree.
781 Comment Controls
783 Perltidy has a number of ways to control the appearance of both block
784 comments and side comments. The term block comment here refers to a
785 full-line comment, whereas side comment will refer to a comment which
786 appears on a line to the right of some code.
787 -ibc, --indent-block-comments
789 Block comments normally look best when they are indented to the
790 same level as the code which follows them. This is the default
791 behavior, but you may use -nibc to keep block comments left-
792 justified. Here is an example:
793 # this comment is indented (-ibc, default)
795 if ($task) { yyy(); }
796 The alternative is -nibc:
798 # this comment is not indented (-nibc)
800 if ($task) { yyy(); }
801 See also the next item, -isbc, as well as -sbc, for other ways to
803 have some indented and some outdented block comments.
804 -isbc, --indent-spaced-block-comments
806 If there is no leading space on the line, then the comment will not
807 be indented, and otherwise it may be.
808 If both -ibc and -isbc are set, then -isbc takes priority.
810 -olc, --outdent-long-comments
812 When -olc is set, lines which are full-line (block) comments longer
813 than the value maximum-line-length will have their indentation
814 removed. This is the default; use -nolc to prevent outdenting.
815 -msc=n, --minimum-space-to-comment=n
817 Side comments look best when lined up several spaces to the right
818 of code. Perltidy will try to keep comments at least n spaces to
819 the right. The default is n=4 spaces.
820 -fpsc=n, --fixed-position-side-comment=n
822 This parameter tells perltidy to line up side comments in column
823 number n whenever possible. The default, n=0, is not do do this.
824 -hsc, --hanging-side-comments
826 By default, perltidy tries to identify and align "hanging side
827 comments", which are something like this:
828 my $IGNORE = 0; # This is a side comment
830 # This is a hanging side comment
831 # And so is this
832 A comment is considered to be a hanging side comment if (1) it
834 immediately follows a line with a side comment, or another hanging
835 side comment, and (2) there is some leading whitespace on the line.
836 To deactivate this feature, use -nhsc or --nohanging-side-comments.
837 If block comments are preceded by a blank line, or have no leading
838 whitespace, they will not be mistaken as hanging side comments.
839 Closing Side Comments
841 A closing side comment is a special comment which perltidy can
842 automatically create and place after the closing brace of a code
843 block. They can be useful for code maintenance and debugging. The
844 command -csc (or --closing-side-comments) adds or updates closing
845 side comments. For example, here is a small code snippet
846 sub message {
848 if ( !defined( $_[0] ) ) {
849 print("Hello, World\n");
850 }
851 else {
852 print( $_[0], "\n" );
853 }
854 }
855 And here is the result of processing with "perltidy -csc":
857 sub message {
859 if ( !defined( $_[0] ) ) {
860 print("Hello, World\n");
861 }
862 else {
863 print( $_[0], "\n" );
864 }
865 } ## end sub message
866 A closing side comment was added for "sub message" in this case,
868 but not for the "if" and "else" blocks, because they were below the
869 6 line cutoff limit for adding closing side comments. This limit
870 may be changed with the -csci command, described below.
871 The command -dcsc (or --delete-closing-side-comments) reverses this
873 process and removes these comments.
874 Several commands are available to modify the behavior of these two
876 basic commands, -csc and -dcsc:
877 -csci=n, or --closing-side-comment-interval=n
879 where "n" is the minimum number of lines that a block must have
880 in order for a closing side comment to be added. The default
881 value is "n=6". To illustrate:
882 # perltidy -csci=2 -csc
884 sub message {
885 if ( !defined( $_[0] ) ) {
886 print("Hello, World\n");
887 } ## end if ( !defined( $_[0] ))
888 else {
889 print( $_[0], "\n" );
890 } ## end else [ if ( !defined( $_[0] ))
891 } ## end sub message
892 Now the "if" and "else" blocks are commented. However, now
894 this has become very cluttered.
895 -cscp=string, or --closing-side-comment-prefix=string
897 where string is the prefix used before the name of the block
898 type. The default prefix, shown above, is "## end". This
899 string will be added to closing side comments, and it will also
900 be used to recognize them in order to update, delete, and
901 format them. Any comment identified as a closing side comment
902 will be placed just a single space to the right of its closing
903 brace.
904 -cscl=string, or --closing-side-comment-list-string
906 where "string" is a list of block types to be tagged with
907 closing side comments. By default, all code block types
908 preceded by a keyword or label (such as "if", "sub", and so on)
909 will be tagged. The -cscl command changes the default list to
910 be any selected block types; see "Specifying Block Types". For
911 example, the following command requests that only "sub"'s,
912 labels, "BEGIN", and "END" blocks be affected by any -csc or
913 -dcsc operation:
914 -cscl="sub : BEGIN END"
916 -csct=n, or --closing-side-comment-maximum-text=n
918 The text appended to certain block types, such as an "if"
919 block, is whatever lies between the keyword introducing the
920 block, such as "if", and the opening brace. Since this might
921 be too much text for a side comment, there needs to be a limit,
922 and that is the purpose of this parameter. The default value
923 is "n=20", meaning that no additional tokens will be appended
924 to this text after its length reaches 20 characters. Omitted
925 text is indicated with "...". (Tokens, including sub names,
926 are never truncated, however, so actual lengths may exceed
927 this). To illustrate, in the above example, the appended text
928 of the first block is " ( !defined( $_[0] )...". The existing
929 limit of "n=20" caused this text to be truncated, as indicated
930 by the "...". See the next flag for additional control of the
931 abbreviated text.
932 -cscb, or --closing-side-comments-balanced
934 As discussed in the previous item, when the closing-side-
935 comment-maximum-text limit is exceeded the comment text must be
936 truncated. Older versions of perltidy terminated with three
937 dots, and this can still be achieved with -ncscb:
938 perltidy -csc -ncscb
940 } ## end foreach my $foo (sort { $b cmp $a ...
941 However this causes a problem with editors editors which cannot
943 recognize comments or are not configured to do so because they
944 cannot "bounce" around in the text correctly. The -cscb flag
945 has been added to help them by appending appropriate balancing
946 structure:
947 perltidy -csc -cscb
949 } ## end foreach my $foo (sort { $b cmp $a ... })
950 The default is -cscb.
952 -csce=n, or --closing-side-comment-else-flag=n
954 The default, n=0, places the text of the opening "if" statement
955 after any terminal "else".
956 If n=2 is used, then each "elsif" is also given the text of the
958 opening "if" statement. Also, an "else" will include the text
959 of a preceding "elsif" statement. Note that this may result
960 some long closing side comments.
961 If n=1 is used, the results will be the same as n=2 whenever
963 the resulting line length is less than the maximum allowed.
964 =item -cscb, or --closing-side-comments-balanced
965 When using closing-side-comments, and the closing-side-comment-
967 maximum-text limit is exceeded, then the comment text must be
968 abbreviated. It is terminated with three dots if the -cscb
969 flag is negated:
970 perltidy -csc -ncscb
972 } ## end foreach my $foo (sort { $b cmp $a ...
973 This causes a problem with older editors which do not recognize
975 comments because they cannot "bounce" around in the text
976 correctly. The -cscb flag tries to help them by appending
977 appropriate terminal balancing structures:
978 perltidy -csc -cscb
980 } ## end foreach my $foo (sort { $b cmp $a ... })
981 The default is -cscb.
983 -cscw, or --closing-side-comment-warnings
985 This parameter is intended to help make the initial transition
986 to the use of closing side comments. It causes two things to
987 happen if a closing side comment replaces an existing,
988 different closing side comment: first, an error message will
989 be issued, and second, the original side comment will be placed
990 alone on a new specially marked comment line for later
991 attention.
992 The intent is to avoid clobbering existing hand-written side
994 comments which happen to match the pattern of closing side
995 comments. This flag should only be needed on the first run with
996 -csc.
997 Important Notes on Closing Side Comments:
999 · Closing side comments are only placed on lines terminated with
1001 a closing brace. Certain closing styles, such as the use of
1002 cuddled elses (-ce), preclude the generation of some closing
1003 side comments.
1004 · Please note that adding or deleting of closing side comments
1006 takes place only through the commands -csc or -dcsc. The other
1007 commands, if used, merely modify the behavior of these two
1008 commands.
1009 · It is recommended that the -cscw flag be used along with -csc
1011 on the first use of perltidy on a given file. This will
1012 prevent loss of any existing side comment data which happens to
1013 have the csc prefix.
1014 · Once you use -csc, you should continue to use it so that any
1016 closing side comments remain correct as code changes.
1017 Otherwise, these comments will become incorrect as the code is
1018 updated.
1019 · If you edit the closing side comments generated by perltidy,
1021 you must also change the prefix to be different from the
1022 closing side comment prefix. Otherwise, your edits will be
1023 lost when you rerun perltidy with -csc. For example, you
1024 could simply change "## end" to be "## End", since the test is
1025 case sensitive. You may also want to use the -ssc flag to keep
1026 these modified closing side comments spaced the same as actual
1027 closing side comments.
1028 · Temporarily generating closing side comments is a useful
1030 technique for exploring and/or debugging a perl script,
1031 especially one written by someone else. You can always remove
1032 them with -dcsc.
1033 Static Block Comments
1035 Static block comments are block comments with a special leading
1036 pattern, "##" by default, which will be treated slightly
1037 differently from other block comments. They effectively behave as
1038 if they had glue along their left and top edges, because they stick
1039 to the left edge and previous line when there is no blank spaces in
1040 those places. This option is particularly useful for controlling
1041 how commented code is displayed.
1042 -sbc, --static-block-comments
1044 When -sbc is used, a block comment with a special leading
1045 pattern, "##" by default, will be treated specially.
1046 Comments so identified are treated as follows:
1048 · If there is no leading space on the line, then the comment
1050 will not be indented, and otherwise it may be,
1051 · no new blank line will be inserted before such a comment,
1053 and
1054 · such a comment will never become a hanging side comment.
1056 For example, assuming @month_of_year is left-adjusted:
1058 @month_of_year = ( # -sbc (default)
1060 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1061 ## 'Dec', 'Nov'
1062 'Nov', 'Dec');
1063 Without this convention, the above code would become
1065 @month_of_year = ( # -nsbc
1067 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1068 ## 'Dec', 'Nov'
1070 'Nov', 'Dec'
1071 );
1072 which is not as clear. The default is to use -sbc. This may
1074 be deactivated with -nsbc.
1075 -sbcp=string, --static-block-comment-prefix=string
1077 This parameter defines the prefix used to identify static block
1078 comments when the -sbc parameter is set. The default prefix is
1079 "##", corresponding to "-sbcp=##". The prefix is actually part
1080 of a perl pattern used to match lines and it must either begin
1081 with "#" or "^#". In the first case a prefix ^\s* will be
1082 added to match any leading whitespace, while in the second case
1083 the pattern will match only comments with no leading
1084 whitespace. For example, to identify all comments as static
1085 block comments, one would use "-sbcp=#". To identify all left-
1086 adjusted comments as static block comments, use "-sbcp='^#'".
1087 Please note that -sbcp merely defines the pattern used to
1089 identify static block comments; it will not be used unless the
1090 switch -sbc is set. Also, please be aware that since this
1091 string is used in a perl regular expression which identifies
1092 these comments, it must enable a valid regular expression to be
1093 formed.
1094 A pattern which can be useful is:
1096 -sbcp=^#{2,}[^\s#]
1098 This pattern requires a static block comment to have at least
1100 one character which is neither a # nor a space. It allows a
1101 line containing only '#' characters to be rejected as a static
1102 block comment. Such lines are often used at the start and end
1103 of header information in subroutines and should not be
1104 separated from the intervening comments, which typically begin
1105 with just a single '#'.
1106 -osbc, --outdent-static-block-comments
1108 The command -osbc will will cause static block comments to be
1109 outdented by 2 spaces (or whatever -ci=n has been set to), if
1110 possible.
1111 Static Side Comments
1113 Static side comments are side comments with a special leading
1114 pattern. This option can be useful for controlling how commented
1115 code is displayed when it is a side comment.
1116 -ssc, --static-side-comments
1118 When -ssc is used, a side comment with a static leading
1119 pattern, which is "##" by default, will be be spaced only a
1120 single space from previous character, and it will not be
1121 vertically aligned with other side comments.
1122 The default is -nssc.
1124 -sscp=string, --static-side-comment-prefix=string
1126 This parameter defines the prefix used to identify static side
1127 comments when the -ssc parameter is set. The default prefix is
1128 "##", corresponding to "-sscp=##".
1129 Please note that -sscp merely defines the pattern used to
1131 identify static side comments; it will not be used unless the
1132 switch -ssc is set. Also, note that this string is used in a
1133 perl regular expression which identifies these comments, so it
1134 must enable a valid regular expression to be formed.
1135 Skipping Selected Sections of Code
1137 Selected lines of code may be passed verbatim to the output without any
1138 formatting. This feature is enabled by default but can be disabled
1139 with the --noformat-skipping or -nfs flag. It should be used sparingly
1140 to avoid littering code with markers, but it might be helpful for
1141 working around occasional problems. For example it might be useful for
1142 keeping the indentation of old commented code unchanged, keeping
1143 indentation of long blocks of aligned comments unchanged, keeping
1144 certain list formatting unchanged, or working around a glitch in
1145 perltidy.
1146 -fs, --format-skipping
1148 This flag, which is enabled by default, causes any code between
1149 special beginning and ending comment markers to be passed to the
1150 output without formatting. The default beginning marker is #<<<
1151 and the default ending marker is #>>> but they may be changed (see
1152 next items below). Additional text may appear on these special
1153 comment lines provided that it is separated from the marker by at
1154 least one space. For example
1155 #<<< do not let perltidy touch this
1157 my @list = (1,
1158 1, 1,
1159 1, 2, 1,
1160 1, 3, 3, 1,
1161 1, 4, 6, 4, 1,);
1162 #>>>
1163 The comment markers may be placed at any location that a block
1165 comment may appear. If they do not appear to be working, use the
1166 -log flag and examine the .LOG file. Use -nfs to disable this
1167 feature.
1168 -fsb=string, --format-skipping-begin=string
1170 The -fsb=string parameter may be used to change the beginning
1171 marker for format skipping. The default is equivalent to
1172 -fsb='#<<<'. The string that you enter must begin with a # and
1173 should be in quotes as necessary to get past the command shell of
1174 your system. It is actually the leading text of a pattern that is
1175 constructed by appending a '\s', so you must also include
1176 backslashes for characters to be taken literally rather than as
1177 patterns.
1178 Some examples show how example strings become patterns:
1180 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
1182 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
1183 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
1184 -fse=string, --format-skipping-end=string
1186 The -fsb=string is the corresponding parameter used to change the
1187 ending marker for format skipping. The default is equivalent to
1188 -fse='#<<<'.
1189 Line Break Control
1191 The parameters in this section control breaks after non-blank lines of
1192 code. Blank lines are controlled separately by parameters in the
1193 section "Blank Line Control".
1194 -fnl, --freeze-newlines
1196 If you do not want any changes to the line breaks within lines of
1197 code in your script, set -fnl, and they will remain fixed, and the
1198 rest of the commands in this section and sections "Controlling List
1199 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
1200 want to use -noll with this.
1201 Note: If you also want to keep your blank lines exactly as they
1203 are, you can use the -fbl flag which is described in the section
1204 "Blank Line Control".
1205 -ce, --cuddled-else
1207 Enable the "cuddled else" style, in which "else" and "elsif" are
1208 follow immediately after the curly brace closing the previous
1209 block. The default is not to use cuddled elses, and is indicated
1210 with the flag -nce or --nocuddled-else. Here is a comparison of
1211 the alternatives:
1212 if ($task) {
1214 yyy();
1215 } else { # -ce
1216 zzz();
1217 }
1218 if ($task) {
1220 yyy();
1221 }
1222 else { # -nce (default)
1223 zzz();
1224 }
1225 -bl, --opening-brace-on-new-line
1227 Use the flag -bl to place the opening brace on a new line:
1228 if ( $input_file eq '-' ) # -bl
1230 {
1231 important_function();
1232 }
1233 This flag applies to all structural blocks, including named sub's
1235 (unless the -sbl flag is set -- see next item).
1236 The default style, -nbl, places an opening brace on the same line
1238 as the keyword introducing it. For example,
1239 if ( $input_file eq '-' ) { # -nbl (default)
1241 -sbl, --opening-sub-brace-on-new-line
1243 The flag -sbl can be used to override the value of -bl for the
1244 opening braces of named sub's. For example,
1245 perltidy -sbl
1247 produces this result:
1249 sub message
1251 {
1252 if (!defined($_[0])) {
1253 print("Hello, World\n");
1254 }
1255 else {
1256 print($_[0], "\n");
1257 }
1258 }
1259 This flag is negated with -nsbl. If -sbl is not specified, the
1261 value of -bl is used.
1262 -asbl, --opening-anonymous-sub-brace-on-new-line
1264 The flag -asbl is like the -sbl flag except that it applies to
1265 anonymous sub's instead of named subs. For example
1266 perltidy -asbl
1268 produces this result:
1270 $a = sub
1272 {
1273 if ( !defined( $_[0] ) ) {
1274 print("Hello, World\n");
1275 }
1276 else {
1277 print( $_[0], "\n" );
1278 }
1279 };
1280 This flag is negated with -nasbl, and the default is -nasbl.
1282 -bli, --brace-left-and-indent
1284 The flag -bli is the same as -bl but in addition it causes one unit
1285 of continuation indentation ( see -ci ) to be placed before an
1286 opening and closing block braces.
1287 For example,
1289 if ( $input_file eq '-' ) # -bli
1291 {
1292 important_function();
1293 }
1294 By default, this extra indentation occurs for blocks of type: if,
1296 elsif, else, unless, for, foreach, sub, while, until, and also with
1297 a preceding label. The next item shows how to change this.
1298 -blil=s, --brace-left-and-indent-list=s
1300 Use this parameter to change the types of block braces for which
1301 the -bli flag applies; see "Specifying Block Types". For example,
1302 -blil='if elsif else' would apply it to only "if/elsif/else"
1303 blocks.
1304 -bar, --opening-brace-always-on-right
1306 The default style, -nbl places the opening code block brace on a
1307 new line if it does not fit on the same line as the opening
1308 keyword, like this:
1309 if ( $bigwasteofspace1 && $bigwasteofspace2
1311 || $bigwasteofspace3 && $bigwasteofspace4 )
1312 {
1313 big_waste_of_time();
1314 }
1315 To force the opening brace to always be on the right, use the -bar
1317 flag. In this case, the above example becomes
1318 if ( $bigwasteofspace1 && $bigwasteofspace2
1320 || $bigwasteofspace3 && $bigwasteofspace4 ) {
1321 big_waste_of_time();
1322 }
1323 A conflict occurs if both -bl and -bar are specified.
1325 -otr, --opening-token-right and related flags
1327 The -otr flag is a hint that perltidy should not place a break
1328 between a comma and an opening token. For example:
1329 # default formatting
1331 push @{ $self->{$module}{$key} },
1332 {
1333 accno => $ref->{accno},
1334 description => $ref->{description}
1335 };
1336 # perltidy -otr
1338 push @{ $self->{$module}{$key} }, {
1339 accno => $ref->{accno},
1340 description => $ref->{description}
1341 };
1342 The flag -otr is actually a synonym for three other flags which can
1344 be used to control parens, hash braces, and square brackets
1345 separately if desired:
1346 -opr or --opening-paren-right
1348 -ohbr or --opening-hash-brace-right
1349 -osbr or --opening-square-bracket-right
1350 Vertical tightness of non-block curly braces, parentheses, and square
1352 brackets.
1353 These parameters control what shall be called vertical tightness.
1354 Here are the main points:
1355 · Opening tokens (except for block braces) are controlled by
1357 -vt=n, or --vertical-tightness=n, where
1358 -vt=0 always break a line after opening token (default).
1360 -vt=1 do not break unless this would produce more than one
1361 step in indentation in a line.
1362 -vt=2 never break a line after opening token
1363 · You must also use the -lp flag when you use the -vt flag; the
1365 reason is explained below.
1366 · Closing tokens (except for block braces) are controlled by
1368 -vtc=n, or --vertical-tightness-closing=n, where
1369 -vtc=0 always break a line before a closing token (default),
1371 -vtc=1 do not break before a closing token which is followed
1372 by a semicolon or another closing token, and is not in
1373 a list environment.
1374 -vtc=2 never break before a closing token.
1375 The rules for -vtc=1 are designed to maintain a reasonable
1377 balance between tightness and readability in complex lists.
1378 · Different controls may be applied to to different token types,
1380 and it is also possible to control block braces; see below.
1381 · Finally, please note that these vertical tightness flags are
1383 merely hints to the formatter, and it cannot always follow
1384 them. Things which make it difficult or impossible include
1385 comments, blank lines, blocks of code within a list, and
1386 possibly the lack of the -lp parameter. Also, these flags may
1387 be ignored for very small lists (2 or 3 lines in length).
1388 Here are some examples:
1390 # perltidy -lp -vt=0 -vtc=0
1392 %romanNumerals = (
1393 one => 'I',
1394 two => 'II',
1395 three => 'III',
1396 four => 'IV',
1397 );
1398 # perltidy -lp -vt=1 -vtc=0
1400 %romanNumerals = ( one => 'I',
1401 two => 'II',
1402 three => 'III',
1403 four => 'IV',
1404 );
1405 # perltidy -lp -vt=1 -vtc=1
1407 %romanNumerals = ( one => 'I',
1408 two => 'II',
1409 three => 'III',
1410 four => 'IV', );
1411 The difference between -vt=1 and -vt=2 is shown here:
1413 # perltidy -lp -vt=1
1415 $init->add(
1416 mysprintf( "(void)find_threadsv(%s);",
1417 cstring( $threadsv_names[ $op->targ ] )
1418 )
1419 );
1420 # perltidy -lp -vt=2
1422 $init->add( mysprintf( "(void)find_threadsv(%s);",
1423 cstring( $threadsv_names[ $op->targ ] )
1424 )
1425 );
1426 With -vt=1, the line ending in "add(" does not combine with the
1428 next line because the next line is not balanced. This can help
1429 with readability, but -vt=2 can be used to ignore this rule.
1430 The tightest, and least readable, code is produced with both
1432 "-vt=2" and "-vtc=2":
1433 # perltidy -lp -vt=2 -vtc=2
1435 $init->add( mysprintf( "(void)find_threadsv(%s);",
1436 cstring( $threadsv_names[ $op->targ ] ) ) );
1437 Notice how the code in all of these examples collapses vertically
1439 as -vt increases, but the indentation remains unchanged. This is
1440 because perltidy implements the -vt parameter by first formatting
1441 as if -vt=0, and then simply overwriting one output line on top of
1442 the next, if possible, to achieve the desired vertical tightness.
1443 The -lp indentation style has been designed to allow this vertical
1444 collapse to occur, which is why it is required for the -vt
1445 parameter.
1446 The -vt=n and -vtc=n parameters apply to each type of container
1448 token. If desired, vertical tightness controls can be applied
1449 independently to each of the closing container token types.
1450 The parameters for controlling parentheses are -pvt=n or
1452 --paren-vertical-tightness=n, and -pcvt=n or
1453 --paren-vertical-tightness-closing=n.
1454 Likewise, the parameters for square brackets are -sbvt=n or
1456 --square-bracket-vertical-tightness=n, and -sbcvt=n or
1457 --square-bracket-vertical-tightness-closing=n.
1458 Finally, the parameters for controlling non-code block braces are
1460 -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or
1461 --brace-vertical-tightness-closing=n.
1462 In fact, the parameter -vt=n is actually just an abbreviation for
1464 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
1465 -pvtc=n -bvtc=n sbvtc=n.
1466 -bbvt=n or --block-brace-vertical-tightness=n
1468 The -bbvt=n flag is just like the -vt=n flag but applies to opening
1469 code block braces.
1470 -bbvt=0 break after opening block brace (default).
1472 -bbvt=1 do not break unless this would produce more than one
1473 step in indentation in a line.
1474 -bbvt=2 do not break after opening block brace.
1475 It is necessary to also use either -bl or -bli for this to work,
1477 because, as with other vertical tightness controls, it is
1478 implemented by simply overwriting a line ending with an opening
1479 block brace with the subsequent line. For example:
1480 # perltidy -bli -bbvt=0
1482 if ( open( FILE, "< $File" ) )
1483 {
1484 while ( $File = <FILE> )
1485 {
1486 $In .= $File;
1487 $count++;
1488 }
1489 close(FILE);
1490 }
1491 # perltidy -bli -bbvt=1
1493 if ( open( FILE, "< $File" ) )
1494 { while ( $File = <FILE> )
1495 { $In .= $File;
1496 $count++;
1497 }
1498 close(FILE);
1499 }
1500 By default this applies to blocks associated with keywords if,
1502 elsif, else, unless, for, foreach, sub, while, until, and also with
1503 a preceding label. This can be changed with the parameter
1504 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
1505 where string is a space-separated list of block types. For more
1506 information on the possible values of this string, see "Specifying
1507 Block Types"
1508 For example, if we want to just apply this style to "if", "elsif",
1510 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
1511 elsif else'".
1512 There is no vertical tightness control for closing block braces;
1514 with the exception of one-line blocks, they will normally remain on
1515 a separate line.
1516 -sot, --stack-opening-tokens and related flags
1518 The -sot flag tells perltidy to "stack" opening tokens when
1519 possible to avoid lines with isolated opening tokens.
1520 For example:
1522 # default
1524 $opt_c = Text::CSV_XS->new(
1525 {
1526 binary => 1,
1527 sep_char => $opt_c,
1528 always_quote => 1,
1529 }
1530 );
1531 # -sot
1533 $opt_c = Text::CSV_XS->new( {
1534 binary => 1,
1535 sep_char => $opt_c,
1536 always_quote => 1,
1537 }
1538 );
1539 For detailed control of individual closing tokens the following
1541 controls can be used:
1542 -sop or --stack-opening-paren
1544 -sohb or --stack-opening-hash-brace
1545 -sosb or --stack-opening-square-bracket
1546 The flag -sot is a synonym for -sop -sohb -sosb.
1548 -sct, --stack-closing-tokens and related flags
1550 The -sct flag tells perltidy to "stack" closing tokens when
1551 possible to avoid lines with isolated closing tokens.
1552 For example:
1554 # default
1556 $opt_c = Text::CSV_XS->new(
1557 {
1558 binary => 1,
1559 sep_char => $opt_c,
1560 always_quote => 1,
1561 }
1562 );
1563 # -sct
1565 $opt_c = Text::CSV_XS->new(
1566 {
1567 binary => 1,
1568 sep_char => $opt_c,
1569 always_quote => 1,
1570 } );
1571 The -sct flag is somewhat similar to the -vtc flags, and in some
1573 cases it can give a similar result. The difference is that the
1574 -vtc flags try to avoid lines with leading opening tokens by
1575 "hiding" them at the end of a previous line, whereas the -sct flag
1576 merely tries to reduce the number of lines with isolated closing
1577 tokens by stacking them but does not try to hide them. For
1578 example:
1579 # -vtc=2
1581 $opt_c = Text::CSV_XS->new(
1582 {
1583 binary => 1,
1584 sep_char => $opt_c,
1585 always_quote => 1, } );
1586 For detailed control of the stacking of individual closing tokens
1588 the following controls can be used:
1589 -scp or --stack-closing-paren
1591 -schb or --stack-closing-hash-brace
1592 -scsb or --stack-closing-square-bracket
1593 The flag -sct is a synonym for -scp -schb -scsb.
1595 -dnl, --delete-old-newlines
1597 By default, perltidy first deletes all old line break locations,
1598 and then it looks for good break points to match the desired line
1599 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
1600 retain all old line break points.
1601 -anl, --add-newlines
1603 By default, perltidy will add line breaks when necessary to create
1604 continuations of long lines and to improve the script appearance.
1605 Use -nanl or --noadd-newlines to prevent any new line breaks.
1606 This flag does not prevent perltidy from eliminating existing line
1608 breaks; see --freeze-newlines to completely prevent changes to line
1609 break points.
1610 Controlling whether perltidy breaks before or after operators
1612 Four command line parameters provide some control over whether a
1613 line break should be before or after specific token types. Two
1614 parameters give detailed control:
1615 -wba=s or --want-break-after=s, and
1617 -wbb=s or --want-break-before=s.
1619 These parameters are each followed by a quoted string, s,
1621 containing a list of token types (separated only by spaces). No
1622 more than one of each of these parameters should be specified,
1623 because repeating a command-line parameter always overwrites the
1624 previous one before perltidy ever sees it.
1625 By default, perltidy breaks after these token types:
1627 % + - * / x != == >= <= =~ !~ < > | &
1628 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
1629 And perltidy breaks before these token types by default:
1631 . << >> -> && || //
1632 To illustrate, to cause a break after a concatenation operator,
1634 '.', rather than before it, the command line would be
1635 -wba="."
1637 As another example, the following command would cause a break
1639 before math operators '+', '-', '/', and '*':
1640 -wbb="+ - / *"
1642 These commands should work well for most of the token types that
1644 perltidy uses (use --dump-token-types for a list). Also try the -D
1645 flag on a short snippet of code and look at the .DEBUG file to see
1646 the tokenization. However, for a few token types there may be
1647 conflicts with hardwired logic which cause unexpected results. One
1648 example is curly braces, which should be controlled with the
1649 parameter bl provided for that purpose.
1650 WARNING Be sure to put these tokens in quotes to avoid having them
1652 misinterpreted by your command shell.
1653 Two additional parameters are available which, though they provide
1655 no further capability, can simplify input are:
1656 -baao or --break-after-all-operators,
1658 -bbao or --break-before-all-operators.
1660 The -baao sets the default to be to break after all of the
1662 following operators:
1663 % + - * / x != == >= <= =~ !~ < > | &
1665 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
1666 . : ? && || and or err xor
1667 and the -bbao flag sets the default to break before all of these
1669 operators. These can be used to define an initial break preference
1670 which can be fine-tuned with the -wba and -wbb flags. For example,
1671 to break before all operators except an = one could use --bbao
1672 -wba='=' rather than listing every single perl operator except = on
1673 a -wbb flag.
1674 Controlling List Formatting
1676 Perltidy attempts to place comma-separated arrays of values in tables
1677 which look good. Its default algorithms usually work well, and they
1678 have been improving with each release, but several parameters are
1679 available to control list formatting.
1680 -boc, --break-at-old-comma-breakpoints
1682 This flag tells perltidy to try to break at all old commas. This
1683 is not the default. Normally, perltidy makes a best guess at list
1684 formatting, and seldom uses old comma breakpoints. Usually this
1685 works well, but consider:
1686 my @list = (1,
1688 1, 1,
1689 1, 2, 1,
1690 1, 3, 3, 1,
1691 1, 4, 6, 4, 1,);
1692 The default formatting will flatten this down to one line:
1694 # perltidy (default)
1696 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
1697 which hides the structure. Using -boc, plus additional flags to
1699 retain the original style, yields
1700 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
1702 my @list = (1,
1703 1, 1,
1704 1, 2, 1,
1705 1, 3, 3, 1,
1706 1, 4, 6, 4, 1,);
1707 A disadvantage of this flag is that all tables in the file must
1709 already be nicely formatted. For another possibility see the -fs
1710 flag in "Skipping Selected Sections of Code".
1711 -mft=n, --maximum-fields-per-table=n
1713 If the computed number of fields for any table exceeds n, then it
1714 will be reduced to n. The default value for n is a large number,
1715 40. While this value should probably be left unchanged as a
1716 general rule, it might be used on a small section of code to force
1717 a list to have a particular number of fields per line, and then
1718 either the -boc flag could be used to retain this formatting, or a
1719 single comment could be introduced somewhere to freeze the
1720 formatting in future applications of perltidy.
1721 # perltidy -mft=2
1723 @month_of_year = (
1724 'Jan', 'Feb',
1725 'Mar', 'Apr',
1726 'May', 'Jun',
1727 'Jul', 'Aug',
1728 'Sep', 'Oct',
1729 'Nov', 'Dec'
1730 );
1731 -cab=n, --comma-arrow-breakpoints=n
1733 A comma which follows a comma arrow, '=>', requires special
1734 consideration. In a long list, it is common to break at all such
1735 commas. This parameter can be used to control how perltidy breaks
1736 at these commas. (However, it will have no effect if old comma
1737 breaks are being forced because -boc is used). The possible values
1738 of n are:
1739 n=0 break at all commas after =>
1741 n=1 stable: break at all commas after => unless this would break
1742 an existing one-line container (default)
1743 n=2 break at all commas after =>, but try to form the maximum
1744 maximum one-line container lengths
1745 n=3 do not treat commas after => specially at all
1746 For example, given the following single line, perltidy by default
1748 will not add any line breaks because it would break the existing
1749 one-line container:
1750 bless { B => $B, Root => $Root } => $package;
1752 Using -cab=0 will force a break after each comma-arrow item:
1754 # perltidy -cab=0:
1756 bless {
1757 B => $B,
1758 Root => $Root
1759 } => $package;
1760 If perltidy is subsequently run with this container broken, then by
1762 default it will break after each '=>' because the container is now
1763 broken. To reform a one-line container, the parameter -cab=2 would
1764 be needed.
1765 The flag -cab=3 can be used to prevent these commas from being
1767 treated specially. In this case, an item such as "01" => 31 is
1768 treated as a single item in a table. The number of fields in this
1769 table will be determined by the same rules that are used for any
1770 other table. Here is an example.
1771 # perltidy -cab=3
1773 my %last_day = (
1774 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
1775 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
1776 "09" => 30, "10" => 31, "11" => 30, "12" => 31
1777 );
1778 Retaining or Ignoring Existing Line Breaks
1780 Several additional parameters are available for controlling the extent
1781 to which line breaks in the input script influence the output script.
1782 In most cases, the default parameter values are set so that, if a
1783 choice is possible, the output style follows the input style. For
1784 example, if a short logical container is broken in the input script,
1785 then the default behavior is for it to remain broken in the output
1786 script.
1787 Most of the parameters in this section would only be required for a
1789 one-time conversion of a script from short container lengths to longer
1790 container lengths. The opposite effect, of converting long container
1791 lengths to shorter lengths, can be obtained by temporarily using a
1792 short maximum line length.
1793 -bol, --break-at-old-logical-breakpoints
1795 By default, if a logical expression is broken at a "&&", "||",
1796 "and", or "or", then the container will remain broken. Also,
1797 breaks at internal keywords "if" and "unless" will normally be
1798 retained. To prevent this, and thus form longer lines, use -nbol.
1799 -bok, --break-at-old-keyword-breakpoints
1801 By default, perltidy will retain a breakpoint before keywords which
1802 may return lists, such as "sort" and <map>. This allows chains of
1803 these operators to be displayed one per line. Use -nbok to prevent
1804 retaining these breakpoints.
1805 -bot, --break-at-old-ternary-breakpoints
1807 By default, if a conditional (ternary) operator is broken at a ":",
1808 then it will remain broken. To prevent this, and thereby form
1809 longer lines, use -nbot.
1810 -iob, --ignore-old-breakpoints
1812 Use this flag to tell perltidy to ignore existing line breaks to
1813 the maximum extent possible. This will tend to produce the longest
1814 possible containers, regardless of type, which do not exceed the
1815 line length limit.
1816 -kis, --keep-interior-semicolons
1818 Use the -kis flag to prevent breaking at a semicolon if there was
1819 no break there in the input file. Normally perltidy places a
1820 newline after each semicolon which terminates a statement unless
1821 several statements are contained within a one-line brace block. To
1822 illustrate, consider the following input lines:
1823 dbmclose(%verb_delim); undef %verb_delim;
1825 dbmclose(%expanded); undef %expanded;
1826 The default is to break after each statement, giving
1828 dbmclose(%verb_delim);
1830 undef %verb_delim;
1831 dbmclose(%expanded);
1832 undef %expanded;
1833 With perltidy -kis the multiple statements are retained:
1835 dbmclose(%verb_delim); undef %verb_delim;
1837 dbmclose(%expanded); undef %expanded;
1838 The statements are still subject to the specified value of maximum-
1840 line-length and will be broken if this maximum is exceeed.
1841 Blank Line Control
1843 Blank lines can improve the readability of a script if they are
1844 carefully placed. Perltidy has several commands for controlling the
1845 insertion, retention, and removal of blank lines.
1846 -fbl, --freeze-blank-lines
1848 Set -fbl if you want to the blank lines in your script to remain
1849 exactly as they are. The rest of the parameters in this section
1850 may then be ignored. (Note: setting the -fbl flag is equivalent to
1851 setting -mbl=0 and -kbl=2).
1852 -bbc, --blanks-before-comments
1854 A blank line will be introduced before a full-line comment. This
1855 is the default. Use -nbbc or --noblanks-before-comments to
1856 prevent such blank lines from being introduced.
1857 -bbs, --blanks-before-subs
1859 A blank line will be introduced before a sub definition, unless it
1860 is a one-liner or preceded by a comment. A blank line will also be
1861 introduced before a package statement and a BEGIN and END block.
1862 This is the default. The intention is to help display the
1863 structure of a program by setting off certain key sections of code.
1864 This is negated with -nbbs or --noblanks-before-subs.
1865 -bbb, --blanks-before-blocks
1867 A blank line will be introduced before blocks of coding delimited
1868 by for, foreach, while, until, and if, unless, in the following
1869 circumstances:
1870 · The block is not preceded by a comment.
1872 · The block is not a one-line block.
1874 · The number of consecutive non-blank lines at the current
1876 indentation depth is at least -lbl (see next section).
1877 This is the default. The intention of this option is to introduce
1879 some space within dense coding. This is negated with -nbbb or
1880 --noblanks-before-blocks.
1881 -lbl=n --long-block-line-count=n
1883 This controls how often perltidy is allowed to add blank lines
1884 before certain block types (see previous section). The default is
1885 8. Entering a value of 0 is equivalent to entering a very large
1886 number.
1887 -mbl=n --maximum-consecutive-blank-lines=n
1889 This parameter specifies the maximum number of consecutive blank
1890 lines which will be output within code sections of a script. The
1891 default is n=1. If the input file has more than n consecutive
1892 blank lines, the number will be reduced to n. If n=0 then no blank
1893 lines will be output (unless all old blank lines are retained with
1894 the -kbl=2 flag of the next section).
1895 This flag obviously does not apply to pod sections, here-documents,
1897 and quotes.
1898 -kbl=n, --keep-old-blank-lines=n
1900 The -kbl=n flag gives you control over how your existing blank
1901 lines are treated.
1902 The possible values of n are:
1904 n=0 ignore all old blank lines
1906 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
1907 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
1908 The default is n=1.
1910 -sob, --swallow-optional-blank-lines
1912 This is equivalent to kbl=0 and is included for compatability with
1913 previous versions.
1914 -nsob, --noswallow-optional-blank-lines
1916 This is equivalent to kbl=1 and is included for compatability with
1917 previous versions.
1918 Styles
1920 A style refers to a convenient collection of existing parameters.
1921 -gnu, --gnu-style
1923 -gnu gives an approximation to the GNU Coding Standards (which do
1924 not apply to perl) as they are sometimes implemented. At present,
1925 this style overrides the default style with the following
1926 parameters:
1927 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
1929 -pbp, --perl-best-practices
1931 -pbp is an abbreviation for the parameters in the book Perl Best
1932 Practices by Damian Conway:
1933 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
1935 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
1936 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
1937 Note that the -st and -se flags make perltidy act as a filter on
1939 one file only. These can be overridden with -nst and -nse if
1940 necessary.
1941 Other Controls
1943 Deleting selected text
1944 Perltidy can selectively delete comments and/or pod documentation.
1945 The command -dac or --delete-all-comments will delete all comments
1946 and all pod documentation, leaving just code and any leading system
1947 control lines.
1948 The command -dp or --delete-pod will remove all pod documentation
1950 (but not comments).
1951 Two commands which remove comments (but not pod) are: -dbc or
1953 --delete-block-comments and -dsc or --delete-side-comments.
1954 (Hanging side comments will be deleted with block comments here.)
1955 The negatives of these commands also work, and are the defaults.
1957 When block comments are deleted, any leading 'hash-bang' will be
1958 retained. Also, if the -x flag is used, any system commands before
1959 a leading hash-bang will be retained (even if they are in the form
1960 of comments).
1961 Writing selected text to a file
1963 When perltidy writes a formatted text file, it has the ability to
1964 also send selected text to a file with a .TEE extension. This text
1965 can include comments and pod documentation.
1966 The command -tac or --tee-all-comments will write all comments and
1968 all pod documentation.
1969 The command -tp or --tee-pod will write all pod documentation (but
1971 not comments).
1972 The commands which write comments (but not pod) are: -tbc or
1974 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
1975 side comments will be written with block comments here.)
1976 The negatives of these commands also work, and are the defaults.
1978 Using a .perltidyrc command file
1980 If you use perltidy frequently, you probably won't be happy until
1981 you create a .perltidyrc file to avoid typing commonly-used
1982 parameters. Perltidy will first look in your current directory for
1983 a command file named .perltidyrc. If it does not find one, it will
1984 continue looking for one in other standard locations.
1985 These other locations are system-dependent, and may be displayed
1987 with the command "perltidy -dpro". Under Unix systems, it will
1988 first look for an environment variable PERLTIDY. Then it will look
1989 for a .perltidyrc file in the home directory, and then for a
1990 system-wide file /usr/local/etc/perltidyrc, and then it will look
1991 for /etc/perltidyrc. Note that these last two system-wide files do
1992 not have a leading dot. Further system-dependent information will
1993 be found in the INSTALL file distributed with perltidy.
1994 Under Windows, perltidy will also search for a configuration file
1996 named perltidy.ini since Windows does not allow files with a
1997 leading period (.). Use "perltidy -dpro" to see the possbile
1998 locations for your system. An example might be C:\Documents and
1999 Settings\All Users\perltidy.ini.
2000 Another option is the use of the PERLTIDY environment variable.
2002 The method for setting environment variables depends upon the
2003 version of Windows that you are using. Instructions for Windows 95
2004 and later versions can be found here:
2005 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
2007 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
2009 be placed in either the user section or the system section. The
2010 later makes the configuration file common to all users on the
2011 machine. Be sure to enter the full path of the configuration file
2012 in the value of the environment variable. Ex.
2013 PERLTIDY=C:\Documents and Settings\perltidy.ini
2014 The configuation file is free format, and simply a list of
2016 parameters, just as they would be entered on a command line. Any
2017 number of lines may be used, with any number of parameters per
2018 line, although it may be easiest to read with one parameter per
2019 line. Blank lines are ignored, and text after a '#' is ignored to
2020 the end of a line.
2021 Here is an example of a .perltidyrc file:
2023 # This is a simple of a .perltidyrc configuration file
2025 # This implements a highly spaced style
2026 -se # errors to standard error output
2027 -w # show all warnings
2028 -bl # braces on new lines
2029 -pt=0 # parens not tight at all
2030 -bt=0 # braces not tight
2031 -sbt=0 # square brackets not tight
2032 The parameters in the .perltidyrc file are installed first, so any
2034 parameters given on the command line will have priority over them.
2035 To avoid confusion, perltidy ignores any command in the .perltidyrc
2037 file which would cause some kind of dump and an exit. These are:
2038 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
2040 There are several options may be helpful in debugging a .perltidyrc
2042 file:
2043 · A very helpful command is --dump-profile or -dpro. It writes a
2045 list of all configuration filenames tested to standard output,
2046 and if a file is found, it dumps the content to standard output
2047 before exiting. So, to find out where perltidy looks for its
2048 configuration files, and which one if any it selects, just
2049 enter
2050 perltidy -dpro
2052 · It may be simplest to develop and test configuration files with
2054 alternative names, and invoke them with -pro=filename on the
2055 command line. Then rename the desired file to .perltidyrc when
2056 finished.
2057 · The parameters in the .perltidyrc file can be switched off with
2059 the -npro option.
2060 · The commands --dump-options, --dump-defaults,
2062 --dump-long-names, and --dump-short-names, all described below,
2063 may all be helpful.
2064 Creating a new abbreviation
2066 A special notation is available for use in a .perltidyrc file for
2067 creating an abbreviation for a group of options. This can be used
2068 to create a shorthand for one or more styles which are frequently,
2069 but not always, used. The notation is to group the options within
2070 curly braces which are preceded by the name of the alias (without
2071 leading dashes), like this:
2072 newword {
2074 -opt1
2075 -opt2
2076 }
2077 where newword is the abbreviation, and opt1, etc, are existing
2079 parameters or other abbreviations. The main syntax requirement is
2080 that the new abbreviation must begin on a new line. Space before
2081 and after the curly braces is optional. For a specific example,
2082 the following line
2083 airy {-bl -pt=0 -bt=0 -sbt=0}
2085 could be placed in a .perltidyrc file, and then invoked at will
2087 with
2088 perltidy -airy somefile.pl
2090 (Either "-airy" or "--airy" may be used).
2092 Skipping leading non-perl commands with -x or --look-for-hash-bang
2094 If your script has leading lines of system commands or other text
2095 which are not valid perl code, and which are separated from the
2096 start of the perl code by a "hash-bang" line, ( a line of the form
2097 "#!...perl" ), you must use the -x flag to tell perltidy not to
2098 parse and format any lines before the "hash-bang" line. This
2099 option also invokes perl with a -x flag when checking the syntax.
2100 This option was originally added to allow perltidy to parse
2101 interactive VMS scripts, but it should be used for any script which
2102 is normally invoked with "perl -x".
2103 Making a file unreadable
2105 The goal of perltidy is to improve the readability of files, but
2106 there are two commands which have the opposite effect, --mangle and
2107 --extrude. They are actually merely aliases for combinations of
2108 other parameters. Both of these strip all possible whitespace, but
2109 leave comments and pod documents, so that they are essentially
2110 reversible. The difference between these is that --mangle puts the
2111 fewest possible line breaks in a script while --extrude puts the
2112 maximum possible. Note that these options do not provided any
2113 meaningful obfuscation, because perltidy can be used to reformat
2114 the files. They were originally developed to help test the
2115 tokenization logic of perltidy, but they have other uses. One use
2116 for --mangle is the following:
2117 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
2119 This will form the maximum possible number of one-line blocks (see
2121 next section), and can sometimes help clean up a badly formatted
2122 script.
2123 A similar technique can be used with --extrude instead of --mangle
2125 to make the minimum number of one-line blocks.
2126 Another use for --mangle is to combine it with -dac to reduce the
2128 file size of a perl script.
2129 One-line blocks
2131 There are a few points to note regarding one-line blocks. A one-
2132 line block is something like this,
2133 if ($x > 0) { $y = 1 / $x }
2135 where the contents within the curly braces is short enough to fit
2137 on a single line.
2138 With few exceptions, perltidy retains existing one-line blocks, if
2140 it is possible within the line-length constraint, but it does not
2141 attempt to form new ones. In other words, perltidy will try to
2142 follow the one-line block style of the input file.
2143 If an existing one-line block is longer than the maximum line
2145 length, however, it will be broken into multiple lines. When this
2146 happens, perltidy checks for and adds any optional terminating
2147 semicolon (unless the -nasc option is used) if the block is a code
2148 block.
2149 The main exception is that perltidy will attempt to form new one-
2151 line blocks following the keywords "map", "eval", and "sort",
2152 because these code blocks are often small and most clearly
2153 displayed in a single line.
2154 One-line block rules can conflict with the cuddled-else option.
2156 When the cuddled-else option is used, perltidy retains existing
2157 one-line blocks, even if they do not obey cuddled-else formatting.
2158 Occasionally, when one-line blocks get broken because they exceed
2160 the available line length, the formatting will violate the
2161 requested brace style. If this happens, reformatting the script a
2162 second time should correct the problem.
2163 Debugging
2165 The following flags are available for debugging:
2166 --dump-defaults or -ddf will write the default option set to
2168 standard output and quit
2169 --dump-profile or -dpro will write the name of the current
2171 configuration file and its contents to standard output and quit.
2172 --dump-options or -dop will write current option set to standard
2174 output and quit.
2175 --dump-long-names or -dln will write all command line long names
2177 (passed to Get_options) to standard output and quit.
2178 --dump-short-names or -dsn will write all command line short names
2180 to standard output and quit.
2181 --dump-token-types or -dtt will write a list of all token types to
2183 standard output and quit.
2184 --dump-want-left-space or -dwls will write the hash
2186 %want_left_space to standard output and quit. See the section on
2187 controlling whitespace around tokens.
2188 --dump-want-right-space or -dwrs will write the hash
2190 %want_right_space to standard output and quit. See the section on
2191 controlling whitespace around tokens.
2192 -DEBUG will write a file with extension .DEBUG for each input file
2194 showing the tokenization of all lines of code.
2195 Working with MakeMaker, AutoLoader and SelfLoader
2197 The first $VERSION line of a file which might be eval'd by
2198 MakeMaker is passed through unchanged except for indentation. Use
2199 --nopass-version-line, or -npvl, to deactivate this feature.
2200 If the AutoLoader module is used, perltidy will continue formatting
2202 code after seeing an __END__ line. Use --nolook-for-autoloader, or
2203 -nlal, to deactivate this feature.
2204 Likewise, if the SelfLoader module is used, perltidy will continue
2206 formatting code after seeing a __DATA__ line. Use
2207 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
2208 Working around problems with older version of Perl
2210 Perltidy contains a number of rules which help avoid known
2211 subtleties and problems with older versions of perl, and these
2212 rules always take priority over whatever formatting flags have been
2213 set. For example, perltidy will usually avoid starting a new line
2214 with a bareword, because this might cause problems if "use strict"
2215 is active.
2216 There is no way to override these rules.
2218
2220 The -html master switch
2221 The flag -html causes perltidy to write an html file with extension
2222 .html. So, for example, the following command
2223 perltidy -html somefile.pl
2225 will produce a syntax-colored html file named somefile.pl.html
2227 which may be viewed with a browser.
2228 Please Note: In this case, perltidy does not do any formatting to
2230 the input file, and it does not write a formatted file with
2231 extension .tdy. This means that two perltidy runs are required to
2232 create a fully reformatted, html copy of a script.
2233 The -pre flag for code snippets
2235 When the -pre flag is given, only the pre-formatted section, within
2236 the <PRE> and </PRE> tags, will be output. This simplifies
2237 inclusion of the output in other files. The default is to output a
2238 complete web page.
2239 The -nnn flag for line numbering
2241 When the -nnn flag is given, the output lines will be numbered.
2242 The -toc, or --html-table-of-contents flag
2244 By default, a table of contents to packages and subroutines will be
2245 written at the start of html output. Use -ntoc to prevent this.
2246 This might be useful, for example, for a pod document which
2247 contains a number of unrelated code snippets. This flag only
2248 influences the code table of contents; it has no effect on any
2249 table of contents produced by pod2html (see next item).
2250 The -pod, or --pod2html flag
2252 There are two options for formatting pod documentation. The
2253 default is to pass the pod through the Pod::Html module (which
2254 forms the basis of the pod2html utility). Any code sections are
2255 formatted by perltidy, and the results then merged. Note: perltidy
2256 creates a temporary file when Pod::Html is used; see "FILES".
2257 Also, Pod::Html creates temporary files for its cache.
2258 NOTE: Perltidy counts the number of "=cut" lines, and either moves
2260 the pod text to the top of the html file if there is one "=cut", or
2261 leaves the pod text in its original order (interleaved with code)
2262 otherwise.
2263 Most of the flags accepted by pod2html may be included in the
2265 perltidy command line, and they will be passed to pod2html. In
2266 some cases, the flags have a prefix "pod" to emphasize that they
2267 are for the pod2html, and this prefix will be removed before they
2268 are passed to pod2html. The flags which have the additional "pod"
2269 prefix are:
2270 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
2272 --[no]podverbose --podflush
2273 The flags which are unchanged from their use in pod2html are:
2275 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
2277 --podpath=s --podroot=s
2278 where 's' is an appropriate character string. Not all of these
2280 flags are available in older versions of Pod::Html. See your
2281 Pod::Html documentation for more information.
2282 The alternative, indicated with -npod, is not to use Pod::Html, but
2284 rather to format pod text in italics (or whatever the stylesheet
2285 indicates), without special html markup. This is useful, for
2286 example, if pod is being used as an alternative way to write
2287 comments.
2288 The -frm, or --frames flag
2290 By default, a single html output file is produced. This can be
2291 changed with the -frm option, which creates a frame holding a table
2292 of contents in the left panel and the source code in the right
2293 side. This simplifies code browsing. Assume, for example, that the
2294 input file is MyModule.pm. Then, for default file extension
2295 choices, these three files will be created:
2296 MyModule.pm.html - the frame
2298 MyModule.pm.toc.html - the table of contents
2299 MyModule.pm.src.html - the formatted source code
2300 Obviously this file naming scheme requires that output be directed
2302 to a real file (as opposed to, say, standard output). If this is
2303 not the case, or if the file extension is unknown, the -frm option
2304 will be ignored.
2305 The -text=s, or --html-toc-extension flag
2307 Use this flag to specify the extra file extension of the table of
2308 contents file when html frames are used. The default is "toc".
2309 See "Specifying File Extensions".
2310 The -sext=s, or --html-src-extension flag
2312 Use this flag to specify the extra file extension of the content
2313 file when html frames are used. The default is "src". See
2314 "Specifying File Extensions".
2315 The -hent, or --html-entities flag
2317 This flag controls the use of Html::Entities for html formatting.
2318 By default, the module Html::Entities is used to encode special
2319 symbols. This may not be the right thing for some browser/language
2320 combinations. Use --nohtml-entities or -nhent to prevent this.
2321 Style Sheets
2323 Style sheets make it very convenient to control and adjust the
2324 appearance of html pages. The default behavior is to write a page
2325 of html with an embedded style sheet.
2326 An alternative to an embedded style sheet is to create a page with
2328 a link to an external style sheet. This is indicated with the
2329 -css=filename, where the external style sheet is filename. The
2330 external style sheet filename will be created if and only if it
2331 does not exist. This option is useful for controlling multiple
2332 pages from a single style sheet.
2333 To cause perltidy to write a style sheet to standard output and
2335 exit, use the -ss, or --stylesheet, flag. This is useful if the
2336 style sheet could not be written for some reason, such as if the
2337 -pre flag was used. Thus, for example,
2338 perltidy -html -ss >mystyle.css
2340 will write a style sheet with the default properties to file
2342 mystyle.css.
2343 The use of style sheets is encouraged, but a web page without a
2345 style sheets can be created with the flag -nss. Use this option if
2346 you must to be sure that older browsers (roughly speaking, versions
2347 prior to 4.0 of Netscape Navigator and Internet Explorer) can
2348 display the syntax-coloring of the html files.
2349 Controlling HTML properties
2351 Note: It is usually more convenient to accept the default
2352 properties and then edit the stylesheet which is produced.
2353 However, this section shows how to control the properties with
2354 flags to perltidy.
2355 Syntax colors may be changed from their default values by flags of
2357 the either the long form, -html-color-xxxxxx=n, or more
2358 conveniently the short form, -hcx=n, where xxxxxx is one of the
2359 following words, and x is the corresponding abbreviation:
2360 Token Type xxxxxx x
2362 ---------- -------- --
2363 comment comment c
2364 number numeric n
2365 identifier identifier i
2366 bareword, function bareword w
2367 keyword keyword k
2368 quite, pattern quote q
2369 here doc text here-doc-text h
2370 here doc target here-doc-target hh
2371 punctuation punctuation pu
2372 parentheses paren p
2373 structural braces structure s
2374 semicolon semicolon sc
2375 colon colon co
2376 comma comma cm
2377 label label j
2378 sub definition name subroutine m
2379 pod text pod-text pd
2380 A default set of colors has been defined, but they may be changed
2382 by providing values to any of the following parameters, where n is
2383 either a 6 digit hex RGB color value or an ascii name for a color,
2384 such as 'red'.
2385 To illustrate, the following command will produce an html file
2387 somefile.pl.html with "aqua" keywords:
2388 perltidy -html -hck=00ffff somefile.pl
2390 and this should be equivalent for most browsers:
2392 perltidy -html -hck=aqua somefile.pl
2394 Perltidy merely writes any non-hex names that it sees in the html
2396 file. The following 16 color names are defined in the HTML 3.2
2397 standard:
2398 black => 000000,
2400 silver => c0c0c0,
2401 gray => 808080,
2402 white => ffffff,
2403 maroon => 800000,
2404 red => ff0000,
2405 purple => 800080,
2406 fuchsia => ff00ff,
2407 green => 008000,
2408 lime => 00ff00,
2409 olive => 808000,
2410 yellow => ffff00
2411 navy => 000080,
2412 blue => 0000ff,
2413 teal => 008080,
2414 aqua => 00ffff,
2415 Many more names are supported in specific browsers, but it is
2417 safest to use the hex codes for other colors. Helpful color tables
2418 can be located with an internet search for "HTML color tables".
2419 Besides color, two other character attributes may be set: bold, and
2421 italics. To set a token type to use bold, use the flag
2422 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
2423 names from the above table. Conversely, to set a token type to NOT
2424 use bold, use --nohtml-bold-xxxxxx or -nhbx.
2425 Likewise, to set a token type to use an italic font, use the flag
2427 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
2428 or short names from the above table. And to set a token type to
2429 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
2430 For example, to use bold braces and lime color, non-bold, italics
2432 keywords the following command would be used:
2433 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
2435 The background color can be specified with
2437 --html-color-background=n, or -hcbg=n for short, where n is a 6
2438 character hex RGB value. The default color of text is the value
2439 given to punctuation, which is black as a default.
2440 Here are some notes and hints:
2442 1. If you find a preferred set of these parameters, you may want to
2444 create a .perltidyrc file containing them. See the perltidy man
2445 page for an explanation.
2446 2. Rather than specifying values for these parameters, it is
2448 probably easier to accept the defaults and then edit a style sheet.
2449 The style sheet contains comments which should make this easy.
2450 3. The syntax-colored html files can be very large, so it may be
2452 best to split large files into smaller pieces to improve download
2453 times.
2454
2456 Specifying Block Types
2457 Several parameters which refer to code block types may be customized by
2458 also specifying an associated list of block types. The type of a block
2459 is the name of the keyword which introduces that block, such as if,
2460 else, or sub. An exception is a labeled block, which has no keyword,
2461 and should be specified with just a colon.
2462 For example, the following parameter specifies "sub", labels, "BEGIN",
2464 and "END" blocks:
2465 -cscl="sub : BEGIN END"
2467 (the meaning of the -cscl parameter is described above.) Note that
2469 quotes are required around the list of block types because of the
2470 spaces.
2471 Specifying File Extensions
2473 Several parameters allow default file extensions to be overridden. For
2474 example, a backup file extension may be specified with -bext=ext, where
2475 ext is some new extension. In order to provides the user some
2476 flexibility, the following convention is used in all cases to decide if
2477 a leading '.' should be used. If the extension "ext" begins with
2478 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
2479 an intermediate '.' (or perhaps an '_' on VMS systems). Otherwise, it
2480 will be appended directly.
2481 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
2483 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
2484 is added, so again the backup file is somefile.pl.old. For "-bext=~",
2485 then no dot is added, and the backup file will be somefile.pl~ .
2486
2488 The following list shows all short parameter names which allow a prefix
2489 'n' to produce the negated form:
2490 D anl asc aws b bbb bbc bbs bl bli boc bok bol bot ce
2492 csc dac dbc dcsc ddf dln dnl dop dp dpro dsc dsm dsn dtt dwls
2493 dwrs dws f fll frm fs hsc html ibc icb icp iob isbc lal log
2494 lp lsl ohbr okw ola oll opr opt osbr otr ple ple pod pvl q
2495 sbc sbl schb scp scsb sct se sfp sfs skp sob sohb sop sosb sot
2496 ssc st sts syn t tac tbc toc tp tqw tsc w x bar kis
2497 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
2499 may be used.
2500
2502 Parsing Limitations
2503 Perltidy should work properly on most perl scripts. It does a lot
2504 of self-checking, but still, it is possible that an error could be
2505 introduced and go undetected. Therefore, it is essential to make
2506 careful backups and to test reformatted scripts.
2507 The main current limitation is that perltidy does not scan modules
2509 included with 'use' statements. This makes it necessary to guess
2510 the context of any bare words introduced by such modules. Perltidy
2511 has good guessing algorithms, but they are not infallible. When it
2512 must guess, it leaves a message in the log file.
2513 If you encounter a bug, please report it.
2515 What perltidy does not parse and format
2517 Perltidy indents but does not reformat comments and "qw" quotes.
2518 Perltidy does not in any way modify the contents of here documents
2519 or quoted text, even if they contain source code. (You could,
2520 however, reformat them separately). Perltidy does not format
2521 'format' sections in any way. And, of course, it does not modify
2522 pod documents.
2523
2525 Temporary files
2526 Under the -html option with the default --pod2html flag, a
2527 temporary file is required to pass text to Pod::Html. Unix systems
2528 will try to use the POSIX tmpnam() function. Otherwise the file
2529 perltidy.TMP will be temporarily created in the current working
2530 directory.
2531 Special files when standard input is used
2533 When standard input is used, the log file, if saved, is
2534 perltidy.LOG, and any errors are written to perltidy.ERR unless the
2535 -se flag is set. These are saved in the current working directory.
2536 Files overwritten
2538 The following file extensions are used by perltidy, and files with
2539 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
2540 and/or .tdy, .html, and .bak, depending on the run type and
2541 settings.
2542 Files extensions limitations
2544 Perltidy does not operate on files for which the run could produce
2545 a file with a duplicated file extension. These extensions include
2546 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
2547 type. The purpose of this rule is to prevent generating confusing
2548 filenames such as somefile.tdy.tdy.tdy.
2549
2551 perlstyle(1), Perl::Tidy(3)
2552
2554 This man page documents perltidy version 20090616.
2555
2557 Michael Cartmell supplied code for adaptation to VMS and helped with
2558 v-strings.
2559 Yves Orton supplied code for adaptation to the various versions of
2561 Windows.
2562 Axel Rose supplied a patch for MacPerl.
2564 Hugh S. Myers designed and implemented the initial Perl::Tidy module
2566 interface.
2567 Many others have supplied key ideas, suggestions, and bug reports; see
2569 the CHANGES file.
2570
2572 Steve Hancock
2573 email: perltidy at users.sourceforge.net
2574 http://perltidy.sourceforge.net
2575
2577 Copyright (c) 2000-2008 by Steve Hancock
2578
2580 This package is free software; you can redistribute it and/or modify it
2581 under the terms of the "GNU General Public License".
2582 Please refer to the file "COPYING" for details.
2584
2586 This package is distributed in the hope that it will be useful, but
2587 WITHOUT ANY WARRANTY; without even the implied warranty of
2588 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
2589 See the "GNU General Public License" for more details.
2591perl v5.10.1 2009-06-16 PERLTIDY(1)